home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / awt / TextField.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  16.3 KB  |  548 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)TextField.java    1.55 98/08/19
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.peer.TextFieldPeer;
  17. import java.awt.event.*;
  18. import java.io.ObjectOutputStream;
  19. import java.io.ObjectInputStream;
  20. import java.io.IOException;
  21.  
  22.  
  23. /**
  24.  * A <code>TextField</code> object is a text component
  25.  * that allows for the editing of a single line of text.
  26.  * <p>
  27.  * For example, the following image depicts a frame with four
  28.  * text fields of varying widths. Two of these text fields
  29.  * display the predefined text <code>"Hello"</code>.
  30.  * <p>
  31.  * <img src="doc-files/TextField-1.gif"
  32.  * ALIGN=center HSPACE=10 VSPACE=7>
  33.  * <p>
  34.  * Here is the code that produces these four text fields:
  35.  * <p>
  36.  * <hr><blockquote><pre>
  37.  * TextField tf1, tf2, tf3, tf4;
  38.  * // a blank text field
  39.  * tf1 = new TextField();
  40.  * // blank field of 20 columns
  41.  * tf2 = new TextField("", 20);
  42.  * // predefined text displayed
  43.  * tf3 = new TextField("Hello!");
  44.  * // predefined text in 30 columns
  45.  * tf4 = new TextField("Hello", 30);
  46.  * </pre></blockquote><hr>
  47.  * <p>
  48.  * Every time the user types a key in the text field, AWT
  49.  * sends two action events to the text field. The first
  50.  * one represents the key press and the second one,
  51.  * the key release. Each action event embodies the state
  52.  * of the system at the time that some action occurred.
  53.  * The properties of an action event indicate which
  54.  * key was pressed, what modifier keys were also pressed,
  55.  * and the time at which the event occurred.
  56.  * <p>
  57.  * Since the event is an instance of <code>ActionEvent</code>,
  58.  * the <code>TextField</code> class's <code>processEvent</code>
  59.  * method examines the event and passes it along to
  60.  * <code>processActionEvent</code>. The latter method redirects the
  61.  * event to any <code>ActionListener</code> objects that have
  62.  * registered an interest in action events generated by this
  63.  * text field.
  64.  *
  65.  * @version    1.55, 08/19/98
  66.  * @author     Sami Shaio
  67.  * @see         java.awt.event.ActionEvent
  68.  * @see         java.awt.TextField#processEvent
  69.  * @see         java.awt.TextField#processActionEvent
  70.  * @since       JDK1.0
  71.  */
  72. public class TextField extends TextComponent {
  73.  
  74.     /**
  75.      * The number of columns in the TextField.
  76.      * If this value is negative, an IllegalArgumentException
  77.      * is thrown when trying to set the Columns.
  78.      *
  79.      * @serial
  80.      * @see setColumns()
  81.      * @see getColumns()
  82.      */
  83.     int columns;
  84.  
  85.     /**
  86.      * The echo character, which is used when
  87.      * the user wishes to disguise the characters
  88.      * typed into the text field.
  89.      * To set the echoChar, echoCharIsSet must be set to
  90.      * <code>true</code>.
  91.      * The Disguises are removed if echoChar = <code>0</code>
  92.      *
  93.      * @serial
  94.      * @see getEchoChar()
  95.      * @see setEchoChar()
  96.      * @see echoCharIsSet()
  97.      */
  98.     char echoChar;
  99.  
  100.     transient ActionListener actionListener;
  101.  
  102.     private static final String base = "textfield";
  103.     private static int nameCounter = 0;
  104.  
  105.     /*
  106.      * JDK 1.1 serialVersionUID
  107.      */
  108.     private static final long serialVersionUID = -2966288784432217853L;
  109.  
  110.     /**
  111.      * Initialize JNI field and method ids 
  112.      */
  113.     private static native void initIDs();
  114.  
  115.     static {
  116.         /* ensure that the necessary native libraries are loaded */
  117.     Toolkit.loadLibraries();
  118.     initIDs();
  119.     }
  120.  
  121.     /**
  122.      * Constructs a new text field.
  123.      */
  124.     public TextField() {
  125.     this("", 0);
  126.     }
  127.  
  128.     /**
  129.      * Constructs a new text field initialized with the specified text.
  130.      * @param      text       the text to be displayed. If
  131.      *             <code>text</code> is <code>null</code>, the empty
  132.      *             string <code>""</code> will be displayed.
  133.      */
  134.     public TextField(String text) {
  135.         this(text, (text != null) ? text.length() : 0);
  136.     }
  137.  
  138.     /**
  139.      * Constructs a new empty TextField with the specified number of columns.
  140.      * A column is an approximate average character 
  141.      * width that is platform-dependent.
  142.      * @param columns the number of columns
  143.      */
  144.     public TextField(int columns) {
  145.     this("", columns);
  146.     }
  147.  
  148.     /**
  149.      * Constructs a new text field initialized with the specified text
  150.      * to be displayed, and wide enough to hold the specified
  151.      * number of columns. A column is an approximate average character
  152.      * width that is platform-dependent.
  153.      * @param      text       the text to be displayed. If
  154.      *             <code>text</code> is <code>null</code>, the empty
  155.      *             string <code>""</code> will be displayed.
  156.      * @param      columns    the number of columns.
  157.      */
  158.     public TextField(String text, int columns) {
  159.     super(text);
  160.     this.columns = columns;
  161.     }
  162.  
  163.     /**
  164.      * Construct a name for this component.  Called by getName() when the
  165.      * name is null.
  166.      */
  167.     String constructComponentName() {
  168.         synchronized (getClass()) {
  169.         return base + nameCounter++;
  170.     }
  171.     }
  172.  
  173.     /**
  174.      * Creates the TextField's peer.  The peer allows us to modify the
  175.      * appearance of the TextField without changing its functionality.
  176.      */
  177.     public void addNotify() {
  178.         synchronized (getTreeLock()) {
  179.         if (peer == null)
  180.             peer = getToolkit().createTextField(this);
  181.         super.addNotify();
  182.     }
  183.     }
  184.  
  185.     /**
  186.      * Gets the character that is to be used for echoing.
  187.      * <p>
  188.      * An echo character is useful for text fields where
  189.      * user input should not be echoed to the screen, as in
  190.      * the case of a text field for entering a password.
  191.      * @return      the echo character for this text field.
  192.      * @see         java.awt.TextField#echoCharIsSet
  193.      * @see         java.awt.TextField#setEchoChar
  194.      */
  195.     public char getEchoChar() {
  196.     return echoChar;
  197.     }
  198.  
  199.     /**
  200.      * Sets the echo character for this text field.
  201.      * <p>
  202.      * An echo character is useful for text fields where
  203.      * user input should not be echoed to the screen, as in
  204.      * the case of a text field for entering a password.
  205.      * @param       c   the echo character for this text field.
  206.      * @see         java.awt.TextField#echoCharIsSet
  207.      * @see         java.awt.TextField#getEchoChar
  208.      * @since       JDK1.1
  209.      */
  210.     public void setEchoChar(char c) {
  211.     setEchoCharacter(c);
  212.     }
  213.  
  214.     /**
  215.      * @deprecated As of JDK version 1.1,
  216.      * replaced by <code>setEchoChar(char)</code>.
  217.      */
  218.     public synchronized void setEchoCharacter(char c) {
  219.     echoChar = c;
  220.     TextFieldPeer peer = (TextFieldPeer)this.peer;
  221.     if (peer != null) {
  222.         peer.setEchoCharacter(c);
  223.     }
  224.     }
  225.  
  226.     /**
  227.      * Sets the text that is presented by this 
  228.      * text component to be the specified text. 
  229.      * @param       t   the new text.
  230.      * @see         java.awt.TextComponent#getText  
  231.      */
  232.     public void setText(String t) {
  233.         super.setText(t);
  234.  
  235.     // This could change the preferred size of the Component.
  236.     if (valid) {
  237.         invalidate();
  238.     }
  239.     }
  240.  
  241.     /**
  242.      * Indicates whether or not this text field has a
  243.      * character set for echoing.
  244.      * <p>
  245.      * An echo character is useful for text fields where
  246.      * user input should not be echoed to the screen, as in
  247.      * the case of a text field for entering a password.
  248.      * @return     <code>true</code> if this text field has
  249.      *                 a character set for echoing;
  250.      *                 <code>false</code> otherwise.
  251.      * @see        java.awt.TextField#setEchoChar
  252.      * @see        java.awt.TextField#getEchoChar
  253.      */
  254.     public boolean echoCharIsSet() {
  255.     return echoChar != 0;
  256.     }
  257.  
  258.     /**
  259.      * Gets the number of columns in this text field.
  260.      * @return     the number of columns.
  261.      * @see        java.awt.TextField#setColumns
  262.      * @since      JDK1.1ld.
  263.      */
  264.     public int getColumns() {
  265.     return columns;
  266.     }
  267.  
  268.     /**
  269.      * Sets the number of columns in this text field. A column is an 
  270.      * approximate average character width that is platform-dependent.
  271.      * @param      columns   the number of columns.
  272.      * @see        java.awt.TextField#getColumns
  273.      * @exception  IllegalArgumentException   if the value
  274.      *                 supplied for <code>columns</code>
  275.      *                 is less than zero.
  276.      * @since      JDK1.1
  277.      */
  278.     public synchronized void setColumns(int columns) {
  279.     int oldVal = this.columns;
  280.     if (columns < 0) {
  281.         throw new IllegalArgumentException("columns less than zero.");
  282.     }
  283.     if (columns != oldVal) {
  284.         this.columns = columns;
  285.         invalidate();
  286.     }
  287.     }
  288.  
  289.     /**
  290.      * Gets the preferred size of this text field
  291.      * with the specified number of columns.
  292.      * @param     columns the number of columns
  293.      *                 in this text field.
  294.      * @return    the preferred dimensions for
  295.      *                 displaying this text field.
  296.      * @since     JDK1.1
  297.      */
  298.     public Dimension getPreferredSize(int columns) {
  299.         return preferredSize(columns);
  300.     }
  301.  
  302.     /**
  303.      * @deprecated As of JDK version 1.1,
  304.      * replaced by <code>getPreferredSize(int)</code>.
  305.      */
  306.     public Dimension preferredSize(int columns) {
  307.         synchronized (getTreeLock()) {
  308.         TextFieldPeer peer = (TextFieldPeer)this.peer;
  309.         return (peer != null) ?
  310.                peer.preferredSize(columns) :
  311.                super.preferredSize();
  312.         }
  313.     }
  314.  
  315.     /**
  316.      * Gets the preferred size of this text field.
  317.      * @return     the preferred dimensions for
  318.      *                         displaying this text field.
  319.      * @since      JDK1.1
  320.      */
  321.     public Dimension getPreferredSize() {
  322.         return preferredSize();
  323.     }
  324.  
  325.     /**
  326.      * @deprecated As of JDK version 1.1,
  327.      * replaced by <code>getPreferredSize()</code>.
  328.      */
  329.     public Dimension preferredSize() {
  330.         synchronized (getTreeLock()) {
  331.         return (columns > 0) ?
  332.                preferredSize(columns) :
  333.                super.preferredSize();
  334.         }
  335.     }
  336.  
  337.     /**
  338.      * Gets the minumum dimensions for a text field with
  339.      * the specified number of columns.
  340.      * @param    columns   the number of columns in
  341.      *                          this text field.
  342.      * @since    JDK1.1
  343.      */
  344.     public Dimension getMinimumSize(int columns) {
  345.         return minimumSize(columns);
  346.     }
  347.  
  348.     /**
  349.      * @deprecated As of JDK version 1.1,
  350.      * replaced by <code>getMinimumSize(int)</code>.
  351.      */
  352.     public Dimension minimumSize(int columns) {
  353.         synchronized (getTreeLock()) {
  354.         TextFieldPeer peer = (TextFieldPeer)this.peer;
  355.         return (peer != null) ?
  356.                peer.minimumSize(columns) :
  357.                super.minimumSize();
  358.         }
  359.     }
  360.  
  361.     /**
  362.      * Gets the minumum dimensions for this text field.
  363.      * @return     the minimum dimensions for
  364.      *                  displaying this text field.
  365.      * @since      JDK1.1
  366.      */
  367.     public Dimension getMinimumSize() {
  368.         return minimumSize();
  369.     }
  370.  
  371.     /**
  372.      * @deprecated As of JDK version 1.1,
  373.      * replaced by <code>getMinimumSize()</code>.
  374.      */
  375.     public Dimension minimumSize() {
  376.         synchronized (getTreeLock()) {
  377.         return (columns > 0) ?
  378.                minimumSize(columns) :
  379.                super.minimumSize();
  380.         }
  381.     }
  382.  
  383.     /**
  384.      * Adds the specified action listener to recieve
  385.      * action events from this text field.
  386.      * If l is null, no exception is thrown and no action is performed.
  387.      *
  388.      * @param      l the action listener.
  389.      * @see        java.awt.event#ActionListener
  390.      * @see        java.awt.TextField#removeActionListener
  391.      * @since      JDK1.1
  392.      */
  393.     public synchronized void addActionListener(ActionListener l) {
  394.     if (l == null) {
  395.         return;
  396.     }
  397.     actionListener = AWTEventMulticaster.add(actionListener, l);
  398.         newEventsOnly = true;
  399.     }
  400.  
  401.     /**
  402.      * Removes the specified action listener so that it no longer
  403.      * receives action events from this text field.
  404.      * If l is null, no exception is thrown and no action is performed.
  405.      *
  406.      * @param          l the action listener.
  407.      * @see            java.awt.event#ActionListener
  408.      * @see            java.awt.TextField#addActionListener
  409.      * @since          JDK1.1
  410.      */
  411.     public synchronized void removeActionListener(ActionListener l) {
  412.     if (l == null) {
  413.         return;
  414.     }
  415.     actionListener = AWTEventMulticaster.remove(actionListener, l);
  416.     }
  417.  
  418.     // REMIND: remove when filtering is done at lower level
  419.     boolean eventEnabled(AWTEvent e) {
  420.         if (e.id == ActionEvent.ACTION_PERFORMED) {
  421.             if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0 ||
  422.                 actionListener != null) {
  423.                 return true;
  424.             }
  425.             return false;
  426.         }
  427.         return super.eventEnabled(e);
  428.     }
  429.  
  430.     /**
  431.      * Processes events on this text field. If the event
  432.      * is an instance of <code>ActionEvent</code>,
  433.      * it invokes the <code>processActionEvent</code>
  434.      * method. Otherwise, it invokes <code>processEvent</code>
  435.      * on the superclass.
  436.      * @param      e the event.
  437.      * @see        java.awt.event.ActionEvent
  438.      * @see        java.awt.TextField#processActionEvent
  439.      * @since      JDK1.1
  440.      */
  441.     protected void processEvent(AWTEvent e) {
  442.         if (e instanceof ActionEvent) {
  443.             processActionEvent((ActionEvent)e);
  444.             return;
  445.         }
  446.     super.processEvent(e);
  447.     }
  448.  
  449.     /**
  450.      * Processes action events occurring on this text field by
  451.      * dispatching them to any registered
  452.      * <code>ActionListener</code> objects.
  453.      * <p>
  454.      * This method is not called unless action events are
  455.      * enabled for this component. Action events are enabled
  456.      * when one of the following occurs:
  457.      * <p><ul>
  458.      * <li>An <code>ActionListener</code> object is registered
  459.      * via <code>addActionListener</code>.
  460.      * <li>Action events are enabled via <code>enableEvents</code>.
  461.      * </ul>
  462.      * @param       e the action event.
  463.      * @see         java.awt.event.ActionListener
  464.      * @see         java.awt.TextField#addActionListener
  465.      * @see         java.awt.Component#enableEvents
  466.      * @since       JDK1.1
  467.      */
  468.     protected void processActionEvent(ActionEvent e) {
  469.         if (actionListener != null) {
  470.             actionListener.actionPerformed(e);
  471.         }
  472.     }
  473.  
  474.     /**
  475.      * Returns the parameter string representing the state of this
  476.      * text field. This string is useful for debugging.
  477.      * @return      the parameter string of this text field.
  478.      */
  479.     protected String paramString() {
  480.     String str = super.paramString();
  481.     if (echoChar != 0) {
  482.         str += ",echo=" + echoChar;
  483.     }
  484.     return str;
  485.     }
  486.  
  487.  
  488.     /* Serialization support.
  489.      */
  490.     /**
  491.      * The textField Serialized Data Version.
  492.      *
  493.      * @serial
  494.      */
  495.     private int textFieldSerializedDataVersion = 1;
  496.  
  497.     /**
  498.      * Writes default serializable fields to stream.  Writes
  499.      * a list of serializable ItemListener(s) as optional data.
  500.      * The non-serializable ItemListner(s) are detected and
  501.      * no attempt is made to serialize them.
  502.      *
  503.      * @serialData Null terminated sequence of 0 or more pairs.
  504.      *             The pair consists of a String and Object.
  505.      *             The String indicates the type of object and
  506.      *             is one of the following :
  507.      *             itemListenerK indicating and ItemListener object.
  508.      *
  509.      * @see AWTEventMulticaster.save(ObjectOutputStream, String, EventListener)
  510.      * @see java.awt.Component.itemListenerK
  511.      */
  512.     private void writeObject(ObjectOutputStream s)
  513.       throws IOException
  514.     {
  515.       s.defaultWriteObject();
  516.  
  517.       AWTEventMulticaster.save(s, actionListenerK, actionListener);
  518.       s.writeObject(null);
  519.     }
  520.  
  521.     /**
  522.      * Read the ObjectInputStream and if it isnt null
  523.      * add a listener to receive item events fired
  524.      * by the TextField.
  525.      * Unrecognised keys or values will be Ignored.
  526.      * 
  527.      * @see removeActionListener()
  528.      * @see addActionListener()
  529.      */
  530.     private void readObject(ObjectInputStream s)
  531.       throws ClassNotFoundException, IOException
  532.     {
  533.       s.defaultReadObject();
  534.  
  535.       Object keyOrNull;
  536.       while(null != (keyOrNull = s.readObject())) {
  537.     String key = ((String)keyOrNull).intern();
  538.  
  539.     if (actionListenerK == key)
  540.       addActionListener((ActionListener)(s.readObject()));
  541.  
  542.     else // skip value for unrecognized key
  543.       s.readObject();
  544.       }
  545.     }
  546.  
  547. }
  548.